Skip to content

feat: add immutable URI query replacement helpers#10268

Merged
paulbalandan merged 1 commit into
codeigniter4:4.8from
memleakd:feat/uri-query-immutable-helpers
Jun 29, 2026
Merged

feat: add immutable URI query replacement helpers#10268
paulbalandan merged 1 commit into
codeigniter4:4.8from
memleakd:feat/uri-query-immutable-helpers

Conversation

@memleakd

@memleakd memleakd commented Jun 1, 2026

Copy link
Copy Markdown
Contributor

Description

This PR follows up on the recently added URI::withQueryVar() / withQueryVars() helpers by adding the remaining immutable query helpers for the existing mutable query APIs:

$uri = new URI('https://example.com/users?q=bob&page=1');

$next = $uri->withQuery('page=2');

$filtered = $uri->withQueryArray([
    'q'    => 'alice',
    'role' => 'admin',
]);

$withoutPage = $uri->withoutQueryVars('page');

$onlyFilters = $uri->withOnlyQueryVars('q', 'role');

Each method returns a cloned URI and leaves the original instance unchanged.

The naming follows the direction discussed in #10242:

  • setQuery() -> withQuery()
  • setQueryArray() -> withQueryArray()
  • stripQuery() -> withoutQueryVars()
  • keepQuery() -> withOnlyQueryVars()

I kept withQueryParams() out of this because PSR-7 uses that name on ServerRequestInterface, not UriInterface, and withQueryArray() keeps the URI-side API clearer.

Tests cover cloning behavior, query replacement, raw query strings, fragments, filtering/removal, and invalid query strings.

Checklist:

  • Securely signed commits
  • Component(s) with PHPDoc blocks, only if necessary or adds value (without duplication)
  • Unit testing, with >80% coverage
  • User guide updated
  • Conforms to style guide

- add immutable URI helpers for replacing and filtering query vars
- document the full immutable query helper family
- cover clone behavior, raw query strings, fragments, and invalid query strings

Signed-off-by: memleakd <121398829+memleakd@users.noreply.github.com>
@github-actions github-actions Bot added the 4.8 PRs that target the `4.8` branch. label Jun 1, 2026
@memleakd memleakd changed the title feat: add immutable URI query replacement helpers feat: add immutable URI query replacement helpers Jun 1, 2026

@michalsn michalsn left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, this looks like a good direction to me.

One thing I think would make this clearer for users is adding a small table to the URI user guide that lists the mutable query methods next to their immutable alternatives, for example:

Mutable method Immutable alternative
setQuery() withQuery()
setQueryArray() withQueryArray()
addQuery() withQueryVar() / withQueryVars()
stripQuery() withoutQueryVars()
keepQuery() withOnlyQueryVars()

It would also be useful to add a short note that the with*() methods return a cloned URI and do not modify the original instance, while the older methods modify the current instance.

For the mutable methods, could you also add TODO/docblock notes that they should eventually be deprecated in the next major version in favor of the immutable alternatives?

Maybe something like:

@TODO Deprecated in the next major version. Use withQuery() instead for immutability.

adjusted per method.

@michalsn

Copy link
Copy Markdown
Member

Actually, this feels like something for a follow-up PR. If you have time and energy to work on it, I would really appreciate it.

@memleakd

Copy link
Copy Markdown
Contributor Author

Thanks @michalsn, really appreciate the review and approval. I'll leave this PR as-is now and prepare a small follow-up for the docs.

@paulbalandan paulbalandan merged commit 6328f11 into codeigniter4:4.8 Jun 29, 2026
57 checks passed
@paulbalandan

Copy link
Copy Markdown
Member

Thank you, @memleakd

@memleakd memleakd deleted the feat/uri-query-immutable-helpers branch June 29, 2026 10:24
@memleakd

Copy link
Copy Markdown
Contributor Author

Thank you @michalsn, @patel-vansh, @paulbalandan

@paulbalandan paulbalandan added the new feature PRs for new features label Jul 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

4.8 PRs that target the `4.8` branch. new feature PRs for new features

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants